{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Neurons\n",
    "\n",
    "Neurons are the fundamental computational units in `brainpy.state`. This document explains how neurons work, what models are available, and how to use and create them.\n",
    "\n",
    "## Overview\n",
    "\n",
    "In `brainpy.state`, neurons model the dynamics of neural populations. Each neuron model:\n",
    "\n",
    "- Maintains **membrane potential** (voltage)\n",
    "- Integrates **input currents**\n",
    "- Generates **spikes** when threshold is crossed\n",
    "- **Resets** after spiking (various strategies)\n",
    "\n",
    "All neuron models inherit from the base `Neuron` class and follow consistent interfaces.\n",
    "\n",
    "## Basic Usage\n",
    "\n",
    "### Creating Neurons"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:26.859882Z",
     "start_time": "2025-11-13T09:26:26.856372Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import numpy as np\n",
    "\n",
    "import brainpy\n",
    "import brainstate\n",
    "import braintools\n",
    "import brainunit as u\n",
    "import jax.numpy as jnp"
   ],
   "outputs": [],
   "execution_count": 62
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:26.892571Z",
     "start_time": "2025-11-13T09:26:26.882259Z"
    }
   },
   "cell_type": "code",
   "source": "brainstate.environ.set(dt=0.1 * u.ms)",
   "outputs": [],
   "execution_count": 63
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:26.904598Z",
     "start_time": "2025-11-13T09:26:26.900474Z"
    }
   },
   "source": [
    "# Create a population of 100 LIF neurons\n",
    "neurons = brainpy.state.LIF(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms\n",
    ")"
   ],
   "outputs": [],
   "execution_count": 64
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Initializing States\n",
    "\n",
    "Before simulation, initialize neuron states:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:26.923422Z",
     "start_time": "2025-11-13T09:26:26.913797Z"
    }
   },
   "source": [
    "# Initialize all states to default values\n",
    "brainstate.nn.init_all_states(neurons)\n",
    "\n",
    "# Or with specific batch in_size\n",
    "brainstate.nn.init_all_states(neurons, batch_size=32)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LIF(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=soft,\n",
       "  spk_fun=ReluGrad(alpha=0.3, width=1.0),\n",
       "  R=1. * ohm,\n",
       "  tau=10. * msecond,\n",
       "  V_th=-50. * mvolt,\n",
       "  V_rest=-65. * mvolt,\n",
       "  V_reset=-65. * mvolt,\n",
       "  V_initializer=Constant(value=0.0 * mvolt),\n",
       "  V=HiddenState(\n",
       "    value=~float32[32,100] * mvolt\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 65,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 65
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Running Neurons\n",
    "\n",
    "Update neurons by calling them with input current:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:26.957509Z",
     "start_time": "2025-11-13T09:26:26.936911Z"
    }
   },
   "source": [
    "# Single time step - provide input for all neurons\n",
    "# Create input current array matching neuron population in_size\n",
    "input_current = jnp.ones(100) * 2.0 * u.nA  # 100 neurons, each gets 2.0 nA\n",
    "\n",
    "# Access results\n",
    "voltage = neurons.V.value          # Membrane potential\n",
    "spikes = neurons.get_spike()       # Spike output\n",
    "\n",
    "print(f\"Voltage shape: {voltage.shape}\")\n",
    "print(f\"Spikes shape: {spikes.shape}\")"
   ],
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Voltage shape: (32, 100)\n",
      "Spikes shape: (32, 100)\n"
     ]
    }
   ],
   "execution_count": 66
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Available Neuron Models\n",
    "\n",
    "\n",
    "For more neuron models, see the [API Reference](../../api/index.rst).\n",
    "\n",
    "\n",
    "### IF (Integrate-and-Fire)\n",
    "\n",
    "The simplest spiking neuron model.\n",
    "\n",
    "**Mathematical Model:**\n",
    "\n",
    "\n",
    "$$\n",
    "\\tau \\frac{dV}{dt} = -V + R \\cdot I(t)\n",
    "$$\n",
    "**Spike condition:** If :$ V \\geq V_{th} $, emit spike and reset.\n",
    "\n",
    "**Example:**"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:26.977885Z",
     "start_time": "2025-11-13T09:26:26.961663Z"
    }
   },
   "source": [
    "# IF neuron - simple parameters\n",
    "neuron = brainpy.state.IF(\n",
    "    in_size=100,\n",
    "    V_th=1. * u.mV,        # Spike threshold  \n",
    "    tau=20. * u.ms,        # Membrane time constant\n",
    "    R=1. * u.ohm           # Input resistance\n",
    ")\n",
    "\n",
    "# Initialize the neuron\n",
    "import brainstate\n",
    "brainstate.nn.init_all_states(neuron)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "IF(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=soft,\n",
       "  spk_fun=ReluGrad(alpha=0.3, width=1.0),\n",
       "  R=1. * ohm,\n",
       "  tau=20. * msecond,\n",
       "  V_th=1. * mvolt,\n",
       "  V_initializer=Constant(value=0.0 * mvolt),\n",
       "  V=HiddenState(\n",
       "    value=~float32[100] * mvolt\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 67,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 67
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Parameters:**\n",
    "\n",
    "- `in_size`: Number of neurons\n",
    "- `V_rest`: Resting potential\n",
    "- `V_th`: Spike threshold\n",
    "- `V_reset`: Reset potential after spike\n",
    "- `tau`: Membrane time constant\n",
    "- `R`: Input resistance\n",
    "\n",
    "**Use cases:**\n",
    "\n",
    "- Simple rate coding\n",
    "- Fast simulations\n",
    "- Theoretical studies\n",
    "\n",
    "### LIF (Leaky Integrate-and-Fire)\n",
    "\n",
    "The most commonly used spiking neuron model.\n",
    "\n",
    "**Mathematical Model:**\n",
    "\n",
    "\n",
    "$$\n",
    "\\tau \\frac{dV}{dt} = -(V - V_{rest}) + R \\cdot I(t)\n",
    "$$\n",
    "**Spike condition:** If :$V \\geq V_{th}$, emit spike and reset.\n",
    "\n",
    "**Example:**"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.030431Z",
     "start_time": "2025-11-13T09:26:27.017419Z"
    }
   },
   "source": [
    "neuron = brainpy.state.LIF(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    R=1. * u.ohm,\n",
    "    V_initializer=braintools.init.Normal(-65., 5., unit=u.mV)\n",
    ")\n",
    "\n",
    "# Initialize the neuron\n",
    "brainstate.nn.init_all_states(neuron)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LIF(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=soft,\n",
       "  spk_fun=ReluGrad(alpha=0.3, width=1.0),\n",
       "  R=1. * ohm,\n",
       "  tau=10. * msecond,\n",
       "  V_th=-50. * mvolt,\n",
       "  V_rest=-65. * mvolt,\n",
       "  V_reset=-65. * mvolt,\n",
       "  V_initializer=Normal(mean=-65.0, std=5.0),\n",
       "  V=HiddenState(\n",
       "    value=float32[100] * mvolt\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 68,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 68
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Parameters:**\n",
    "\n",
    "All IF parameters, plus:\n",
    "\n",
    "- `V_initializer`: How to initialize membrane potential\n",
    "\n",
    "**Key Features:**\n",
    "\n",
    "- Leak toward resting potential\n",
    "- Realistic temporal integration\n",
    "- Well-studied dynamics\n",
    "\n",
    "**Use cases:**\n",
    "\n",
    "- General spiking neural networks\n",
    "- Cortical neuron modeling\n",
    "- Learning and training\n",
    "\n",
    "### LIFRef (LIF with Refractory Period)\n",
    "\n",
    "LIF neuron with absolute refractory period.\n",
    "\n",
    "**Mathematical Model:**\n",
    "\n",
    "Same as LIF, but after spiking:\n",
    "\n",
    "- Neuron is \"frozen\" for refractory period\n",
    "- No integration during refractory period\n",
    "- More biologically realistic\n",
    "\n",
    "**Example:**"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.083988Z",
     "start_time": "2025-11-13T09:26:27.073064Z"
    }
   },
   "source": [
    "neuron = brainpy.state.LIFRef(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    tau_ref=2. * u.ms,  # Refractory period\n",
    "    R=1. * u.ohm\n",
    ")\n",
    "\n",
    "# Initialize the neuron\n",
    "brainstate.nn.init_all_states(neuron)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LIFRef(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=soft,\n",
       "  spk_fun=ReluGrad(alpha=0.3, width=1.0),\n",
       "  R=1. * ohm,\n",
       "  tau=10. * msecond,\n",
       "  tau_ref=2. * msecond,\n",
       "  V_th=-50. * mvolt,\n",
       "  V_rest=-65. * mvolt,\n",
       "  V_reset=-65. * mvolt,\n",
       "  V_initializer=Constant(value=0.0 * mvolt),\n",
       "  V=HiddenState(\n",
       "    value=~float32[100] * mvolt\n",
       "  ),\n",
       "  last_spike_time=ShortTermState(\n",
       "    value=~float32[100] * msecond\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 69,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 69
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Additional Parameters:**\n",
    "\n",
    "- `tau_ref`: Refractory period duration\n",
    "\n",
    "**Key Features:**\n",
    "\n",
    "- Absolute refractory period\n",
    "- Prevents immediate re-firing\n",
    "- More realistic spike timing\n",
    "\n",
    "**Use cases:**\n",
    "\n",
    "- Precise temporal coding\n",
    "- Biological realism\n",
    "- Rate regulation\n",
    "\n",
    "### ALIF (Adaptive Leaky Integrate-and-Fire)\n",
    "\n",
    "LIF with spike-frequency adaptation.\n",
    "\n",
    "**Mathematical Model:**\n",
    "\n",
    "\n",
    "$$\n",
    "\\begin{aligned}\n",
    "\\tau \\frac{dV}{dt} &= -(V - V_{rest}) - R \\cdot w + R \\cdot I(t) \\\\\n",
    "\\tau_w \\frac{dw}{dt} &= -w\n",
    "\\end{aligned}\n",
    "$$\n",
    "When spike occurs: :$w \\leftarrow w + \\beta$\n",
    "\n",
    "**Example:**"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.130935Z",
     "start_time": "2025-11-13T09:26:27.119447Z"
    }
   },
   "source": [
    "neuron = brainpy.state.ALIF(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    tau_a=200. * u.ms,   # Adaptation time constant\n",
    "    beta=0.1 * u.nA,        # Spike-triggered adaptation\n",
    "    R=1. * u.ohm\n",
    ")\n",
    "\n",
    "# Initialize the neuron\n",
    "brainstate.nn.init_all_states(neuron)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ALIF(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=soft,\n",
       "  spk_fun=ReluGrad(alpha=0.3, width=1.0),\n",
       "  R=1. * ohm,\n",
       "  tau=10. * msecond,\n",
       "  tau_a=200. * msecond,\n",
       "  V_th=-50. * mvolt,\n",
       "  V_reset=-65. * mvolt,\n",
       "  V_rest=-65. * mvolt,\n",
       "  beta=0.1 * namp,\n",
       "  V_initializer=Constant(value=0.0 * mvolt),\n",
       "  a_initializer=Constant(value=0.0),\n",
       "  V=HiddenState(\n",
       "    value=~float32[100] * mvolt\n",
       "  ),\n",
       "  a=HiddenState(\n",
       "    value=ShapedArray(float32[100], weak_type=True)\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 70,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 70
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Additional Parameters:**\n",
    "\n",
    "- `tau_w`: Adaptation time constant\n",
    "- `beta`: Adaptation increment per spike\n",
    "\n",
    "**Key Features:**\n",
    "\n",
    "- Spike-frequency adaptation\n",
    "- Reduced firing with sustained input\n",
    "- More complex dynamics\n",
    "\n",
    "**Use cases:**\n",
    "\n",
    "- Cortical neuron modeling\n",
    "- Sensory adaptation\n",
    "- Complex temporal patterns\n",
    "\n",
    "## Reset Modes\n",
    "\n",
    "BrainPy supports different reset behaviors after spiking:\n",
    "\n",
    "### Soft Reset (Default)\n",
    "\n",
    "Subtract threshold from membrane potential:\n",
    "\n",
    "\n",
    "$$\n",
    "V \\leftarrow V - V_{th}\n",
    "$$"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.199145Z",
     "start_time": "2025-11-13T09:26:27.188524Z"
    }
   },
   "source": [
    "neuron = brainpy.state.LIF(\n",
    "    in_size=100, \n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    spk_reset='soft'\n",
    ")\n",
    "\n",
    "brainstate.nn.init_all_states(neuron)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LIF(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=soft,\n",
       "  spk_fun=ReluGrad(alpha=0.3, width=1.0),\n",
       "  R=1. * ohm,\n",
       "  tau=10. * msecond,\n",
       "  V_th=-50. * mvolt,\n",
       "  V_rest=-65. * mvolt,\n",
       "  V_reset=-65. * mvolt,\n",
       "  V_initializer=Constant(value=0.0 * mvolt),\n",
       "  V=HiddenState(\n",
       "    value=~float32[100] * mvolt\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 71,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 71
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Properties:**\n",
    "\n",
    "- Preserves extra charge above threshold\n",
    "- Allows rapid re-firing\n",
    "- Common in machine learning\n",
    "\n",
    "### Hard Reset\n",
    "\n",
    "Reset to fixed potential:\n",
    "\n",
    "\n",
    "$$\n",
    "V \\leftarrow V_{reset}\n",
    "$$"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.239190Z",
     "start_time": "2025-11-13T09:26:27.229487Z"
    }
   },
   "source": [
    "neuron = brainpy.state.LIF(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    spk_reset='hard'\n",
    ")\n",
    "\n",
    "brainstate.nn.init_all_states(neuron)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LIF(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=hard,\n",
       "  spk_fun=ReluGrad(alpha=0.3, width=1.0),\n",
       "  R=1. * ohm,\n",
       "  tau=10. * msecond,\n",
       "  V_th=-50. * mvolt,\n",
       "  V_rest=-65. * mvolt,\n",
       "  V_reset=-65. * mvolt,\n",
       "  V_initializer=Constant(value=0.0 * mvolt),\n",
       "  V=HiddenState(\n",
       "    value=~float32[100] * mvolt\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 72,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 72
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Properties:**\n",
    "\n",
    "- Discards extra charge\n",
    "- More biologically realistic\n",
    "- Prevents immediate re-firing\n",
    "\n",
    "### Choosing Reset Mode\n",
    "\n",
    "- **Soft reset**: Machine learning, rate coding, fast oscillations\n",
    "- **Hard reset**: Biological modeling, temporal coding, realism\n",
    "\n",
    "## Spike Functions\n",
    "\n",
    "For training spiking neural networks, use surrogate gradients:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.277165Z",
     "start_time": "2025-11-13T09:26:27.267358Z"
    }
   },
   "source": [
    "neuron = brainpy.state.LIF(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    spk_fun=braintools.surrogate.ReluGrad()\n",
    ")\n",
    "\n",
    "brainstate.nn.init_all_states(neuron)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LIF(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=soft,\n",
       "  spk_fun=ReluGrad(alpha=0.3, width=1.0),\n",
       "  R=1. * ohm,\n",
       "  tau=10. * msecond,\n",
       "  V_th=-50. * mvolt,\n",
       "  V_rest=-65. * mvolt,\n",
       "  V_reset=-65. * mvolt,\n",
       "  V_initializer=Constant(value=0.0 * mvolt),\n",
       "  V=HiddenState(\n",
       "    value=~float32[100] * mvolt\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 73,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 73
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Available surrogate functions:\n",
    "\n",
    "- `ReluGrad()`: ReLU-like gradient\n",
    "- `SigmoidGrad()`: Sigmoid-like gradient\n",
    "- `GaussianGrad()`: Gaussian-like gradient\n",
    "- `SuperSpike()`: SuperSpike surrogate\n",
    "\n",
    "See Tutorial 3 for training details.\n",
    "\n",
    "## Advanced Features\n",
    "\n",
    "### Initialization Strategies\n",
    "\n",
    "Different ways to initialize membrane potential:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.319454Z",
     "start_time": "2025-11-13T09:26:27.303637Z"
    }
   },
   "source": [
    "# Constant initialization\n",
    "neuron1 = brainpy.state.LIF(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    V_initializer=braintools.init.Constant(-65., unit=u.mV)\n",
    ")\n",
    "brainstate.nn.init_all_states(neuron1)\n",
    "\n",
    "# Normal distribution\n",
    "neuron2 = brainpy.state.LIF(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    V_initializer=braintools.init.Normal(-65., 5., unit=u.mV)\n",
    ")\n",
    "brainstate.nn.init_all_states(neuron2)\n",
    "\n",
    "# Uniform distribution\n",
    "neuron3 = brainpy.state.LIF(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    V_initializer=braintools.init.Uniform(-70., -60., unit=u.mV)\n",
    ")\n",
    "brainstate.nn.init_all_states(neuron3)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "LIF(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=soft,\n",
       "  spk_fun=ReluGrad(alpha=0.3, width=1.0),\n",
       "  R=1. * ohm,\n",
       "  tau=10. * msecond,\n",
       "  V_th=-50. * mvolt,\n",
       "  V_rest=-65. * mvolt,\n",
       "  V_reset=0. * mvolt,\n",
       "  V_initializer=Uniform(low=-70.0, high=-60.0),\n",
       "  V=HiddenState(\n",
       "    value=float32[100] * mvolt\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 74,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 74
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Accessing Neuron States"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.375509Z",
     "start_time": "2025-11-13T09:26:27.350990Z"
    }
   },
   "source": [
    "# Membrane potential (with units)\n",
    "voltage = neuron.V.value  # Quantity with units\n",
    "\n",
    "# Spike output (binary or real-valued)\n",
    "spikes = neuron.get_spike()\n",
    "\n",
    "# Access underlying array (without units)\n",
    "voltage_array = neuron.V.value.to_decimal(u.mV)"
   ],
   "outputs": [],
   "execution_count": 75
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Batched Simulation\n",
    "\n",
    "Simulate multiple trials in parallel:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.469688Z",
     "start_time": "2025-11-13T09:26:27.386811Z"
    }
   },
   "source": [
    "# Initialize with batch dimension\n",
    "brainstate.nn.init_all_states(neuron, batch_size=32)\n",
    "\n",
    "# Input shape: (batch_in_size, in_size)\n",
    "# For 32 batches of 100 neurons each\n",
    "input_current = jnp.ones((32, 100)) * 2.0 * u.nA\n",
    "neuron(input_current)\n",
    "\n",
    "# Output shape: (batch_in_size, in_size)\n",
    "spikes = neuron.get_spike()\n",
    "print(f\"Spikes shape: {spikes.shape}\")  # Should be (32, 100)"
   ],
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Spikes shape: (32, 100)\n"
     ]
    }
   ],
   "execution_count": 76
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Complete Example\n",
    "\n",
    "Here's a complete example simulating a LIF neuron:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.702508Z",
     "start_time": "2025-11-13T09:26:27.476680Z"
    }
   },
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# Set time step\n",
    "brainstate.environ.set(dt=0.1 * u.ms)\n",
    "\n",
    "# Create neuron\n",
    "neuron = brainpy.state.LIF(\n",
    "    in_size=1,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    spk_reset='hard'\n",
    ")\n",
    "\n",
    "# Initialize\n",
    "brainstate.nn.init_all_states(neuron)\n",
    "\n",
    "# Simulation parameters\n",
    "duration = 200. * u.ms\n",
    "dt = brainstate.environ.get_dt()\n",
    "times = u.math.arange(0. * u.ms, duration, dt)\n",
    "\n",
    "# Input current (step input)\n",
    "def get_input():\n",
    "    t = brainstate.environ.get('t')\n",
    "    return u.math.where(\n",
    "        t > 50*u.ms,\n",
    "        jnp.ones(1) * 20.0 * u.mA,  # Array of in_size 1\n",
    "        jnp.zeros(1) * u.mA,  # Array of in_size 1\n",
    "    )\n",
    "\n",
    "def step_run(i, t):\n",
    "    with brainstate.environ.context(i=i, t=t):\n",
    "        neuron(get_input())\n",
    "        return neuron.V.value, neuron.get_spike()\n",
    "\n",
    "# Run simulation\n",
    "voltages, spikes = brainstate.transform.for_loop(step_run, jnp.arange(times.size), times)\n",
    "\n",
    "# Plot results\n",
    "voltages = u.math.asarray(voltages)\n",
    "times_plot = times.to_decimal(u.ms)\n",
    "voltages_plot = voltages.to_decimal(u.mV).squeeze()  # Remove in_size dimension\n",
    "\n",
    "plt.figure(figsize=(10, 4))\n",
    "plt.plot(times_plot, voltages_plot)\n",
    "plt.axhline(y=-50, color='r', linestyle='--', label='Threshold')\n",
    "plt.xlabel('Time (ms)')\n",
    "plt.ylabel('Membrane Potential (mV)')\n",
    "plt.title('LIF Neuron Response')\n",
    "plt.legend()\n",
    "plt.grid(True, alpha=0.3)\n",
    "plt.tight_layout()\n",
    "plt.show()"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Figure size 1000x400 with 1 Axes>"
      ],
      "image/png": "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dZhT0jmv14uamhrExsbCbud9E6th+VgXy8baWD7WxbKxNpaPtbF8rItlY22RUD5GzGjEkJ1h0B2gpqYGANC3b98wp4SIiIiIiIisrqamBsnJyZ2+b1NnC8s14/V6ceLECSQlJcFms4U7OUFVV1ejb9+++O677+ByucKdHArA8rEulo21sXysi2VjbSwfa2P5WBfLxtoioXyUUqipqUFOTk6Xo/Ec6Q5gt9uRm5sb7mR0i8vlsmwFJJaPlbFsrI3lY10sG2tj+Vgby8e6WDbWZvXy6WqE22DNyfFEREREREREAjDoJiIiIiIiIgoRBt0RyOl0Yvny5XA6neFOCgXB8rEulo21sXysi2VjbSwfa2P5WBfLxtoklQ8XUiMiIiIiIiIKEY50ExEREREREYUIg24iIiIiIiKiEGHQTURERERERBQiDLojzDPPPIP+/fsjNjYW+fn5+PLLL8OdJC2tWrUKl19+OZKSkpCZmYlrr70WRUVFfseMHz8eNpvN79/ChQvDlGK9rFixosPffsiQIb73GxsbUVBQgF69eiExMRHXX389Tp48GcYU66N///4dysZms6GgoAAA201P+/jjjzFt2jTk5OTAZrPhzTff9HtfKYVly5ahd+/eiIuLw8SJE3Hw4EG/YyoqKjBr1iy4XC6kpKRg3rx5qK2t7cFcyNRV2bjdbixZsgTDhw9HQkICcnJyMGfOHJw4ccLvdwRrb4899lgP50Sms7WduXPndvjbT5482e8Ytp3QOVv5BLsO2Ww2FBYW+o5h+wmN7vShu9NPKy4uxtSpUxEfH4/MzEzcf//9aGlp6cmsnBMG3RHk1VdfxX333Yfly5dj165dGDlyJK6++mqUl5eHO2na2bJlCwoKCvDFF19gw4YNcLvdmDRpEurq6vyOW7BgAUpLS33/nnjiiTClWD+XXHKJ39/+008/9b1377334t///jdee+01bNmyBSdOnMB1110XxtTqY/v27X7lsmHDBgDAjBkzfMew3fScuro6jBw5Es8880zQ95944gn88Y9/xLPPPott27YhISEBV199NRobG33HzJo1C1999RU2bNiAt99+Gx9//DFuu+22nsqCWF2VTX19PXbt2oWHHnoIu3btwvr161FUVIRrrrmmw7GPPPKIX3u66667eiL54p2t7QDA5MmT/f72r7zyit/7bDuhc7byMZdL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9OjRavDgwaqxsdH3O9h2Quds5zallKqqqlLx8fFqzZo1HX6e7Sd0ztaHVurs/bSWlhY1bNgwNWnSJLVnzx71/vvvq4yMDLV06dJwZKlbGHRHmKefflr169dPORwOdcUVV6gvvvgi3EnSEoCg/1588UWllFLFxcXqyiuvVGlpacrpdKoLLrhA3X///aqqqiq8CdfEjTfeqHr37q0cDofq06ePuvHGG9WhQ4d87zc0NKjf/OY3KjU1VcXHx6tf/OIXqrS0NIwp1ssHH3ygAKiioiK/19luet6mTZuCnstuvvlmpVTrtmEPPfSQysrKUk6nU1111VUdyu3MmTNq5syZKjExUblcLnXLLbeompqaMORGlq7K5siRI51ehzZt2qSUUmrnzp0qPz9fJScnq9jYWDV06FC1cuVKv6CP/nddlU99fb2aNGmSysjIUDExMSovL08tWLCgwyAJ207onO3cppRSf/nLX1RcXJyqrKzs8PNsP6Fztj60Ut3rpx09elRNmTJFxcXFqfT0dLV48WLldrt7ODfdZ1NKqRANohMRERERERFpjc90ExEREREREYUIg24iIiIiIiKiEGHQTURERERERBQiDLqJiIiIiIiIQoRBNxEREREREVGIMOgmIiIiIiIiChEG3UREREREREQhwqCbiIiIiIiIKEQYdBMREUWwuXPn4tprrw3b58+ePRsrV64M2e8/cOAAcnNzUVdXF7LPICIiCiWbUkqFOxFERETUkc1m6/L95cuX495774VSCikpKT2TKJP//Oc/mDBhAo4dO4bExMSQfc4vf/lLjBw5Eg899FDIPoOIiChUGHQTERFZVFlZme/rV199FcuWLUNRUZHvtcTExJAGu2czf/58REdH49lnnw3p57zzzjtYsGABiouLER0dHdLPIiIiOt84vZyIiMiisrOzff+Sk5Nhs9n8XktMTOwwvXz8+PG46667sGjRIqSmpiIrKwvPPfcc6urqcMsttyApKQkXXHAB3nvvPb/P2r9/P6ZMmYLExERkZWVh9uzZOH36dKdp83g8eP311zFt2jS/1/v3749HH30Uc+bMQWJiIvLy8vCvf/0Lp06dwvTp05GYmIgRI0Zgx44dvp85duwYpk2bhtTUVCQkJOCSSy7Bu+++63v/pz/9KSoqKrBly5Yf+BclIiLqeQy6iYiIhHnppZeQnp6OL7/8EnfddRfuuOMOzJgxAz/60Y+wa9cuTJo0CbNnz0Z9fT0AoLKyEhMmTMCoUaOwY8cOvP/++zh58iRuuOGGTj9j7969qKqqwmWXXdbhvaeeegrjxo3D7t27MXXqVMyePRtz5szBTTfdhF27dmHQoEGYM2cOjMl2BQUFaGpqwscff4x9+/bh8ccf9xvBdzgcuPTSS/HJJ5+c578UERFR6DHoJiIiEmbkyJH4/e9/j8GDB2Pp0qWIjY1Feno6FixYgMGDB2PZsmU4c+YM9u7dCwD405/+hFGjRmHlypUYMmQIRo0ahRdeeAGbNm3CN998E/Qzjh07hqioKGRmZnZ472c/+xluv/1232dVV1fj8ssvx4wZM3DhhRdiyZIl+Prrr3Hy5EkAQHFxMcaNG4fhw4dj4MCB+PnPf44rr7zS73fm5OTg2LFj5/kvRUREFHoMuomIiIQZMWKE7+uoqCj06tULw4cP972WlZUFACgvLwfQuiDapk2bfM+IJyYmYsiQIQCAw4cPB/2MhoYGOJ3OoIu9mT/f+KyuPv/uu+/Go48+inHjxmH58uW+mwFmcXFxvpF5IiKiSMKgm4iISJiYmBi/7202m99rRqDs9XoBALW1tZg2bRr27Nnj9+/gwYMdRpwN6enpqK+vR3Nzc5efb3xWV58/f/58fPvtt5g9ezb27duHyy67DE8//bTf76yoqEBGRkb3/gBEREQWwqCbiIhIc6NHj8ZXX32F/v3744ILLvD7l5CQEPRnLr30UgCt+2ifD3379sXChQuxfv16LF68GM8995zf+/v378eoUaPOy2cRERH1JAbdREREmisoKEBFRQVmzpyJ7du34/Dhw/jggw9wyy23wOPxBP2ZjIwMjB49Gp9++ukP/vxFixbhgw8+wJEjR7Br1y5s2rQJQ4cO9b1/9OhRlJSUYOLEiT/4s4iIiHoag24iIiLN5eTk4LPPPoPH48GkSZMwfPhwLFq0CCkpKbDbO+8qzJ8/Hy+//PIP/nyPx4OCggIMHToUkydPxoUXXog///nPvvdfeeUVTJo0CXl5eT/4s4iIiHqaTRn7dRARERGdg4aGBlx00UV49dVXMXbs2JB8RnNzMwYPHoy//e1vGDduXEg+g4iIKJQ40k1ERET/k7i4OPz1r3/F6dOnQ/YZxcXFeOCBBxhwExFRxOJINxEREREREVGIcKSbiIiIiIiIKEQYdBMRERERERGFCINuIiIiIiIiohBh0E1EREREREQUIgy6iYiIiIiIiEKEQTcRERERERFRiDDoJiIiIiIiIgoRBt1EREREREREIcKgm4iIiIiIiChEGHQTERERERERhcj/B8YTwbFYo4QQAAAAAElFTkSuQmCC"
     },
     "metadata": {},
     "output_type": "display_data",
     "jetTransient": {
      "display_id": null
     }
    }
   ],
   "execution_count": 77
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating Custom Neurons\n",
    "\n",
    "You can create custom neuron models by inheriting from `Neuron`:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.715478Z",
     "start_time": "2025-11-13T09:26:27.709840Z"
    }
   },
   "source": [
    "from brainpy.state import Neuron\n",
    "\n",
    "class MyNeuron(Neuron):\n",
    "    def __init__(self, in_size, tau, V_th, **kwargs):\n",
    "        super().__init__(in_size, **kwargs)\n",
    "\n",
    "        # Store parameters\n",
    "        self.tau = tau\n",
    "        self.V_th = V_th\n",
    "\n",
    "        # Initialize states\n",
    "        self.V = brainstate.ShortTermState(\n",
    "            braintools.init.Constant(0., unit=u.mV)(in_size)\n",
    "        )\n",
    "        self.spike = brainstate.ShortTermState(\n",
    "            jnp.zeros(in_size)\n",
    "        )\n",
    "\n",
    "    def update(self, x):\n",
    "        # Get time step\n",
    "        dt = brainstate.environ.get_dt()\n",
    "\n",
    "        # Update membrane potential (custom dynamics)\n",
    "        dV = (-self.V.value + x) / self.tau * dt\n",
    "        V_new = self.V.value + dV\n",
    "\n",
    "        # Check for spikes\n",
    "        spike = (V_new >= self.V_th).astype(float)\n",
    "\n",
    "        # Reset\n",
    "        V_new = jnp.where(spike > 0, 0. * u.mV, V_new)\n",
    "\n",
    "        # Update states\n",
    "        self.V.value = V_new\n",
    "        self.spike.value = spike\n",
    "\n",
    "        return spike\n",
    "\n",
    "    def get_spike(self):\n",
    "        return self.spike.value"
   ],
   "outputs": [],
   "execution_count": 78
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Usage:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.758920Z",
     "start_time": "2025-11-13T09:26:27.752520Z"
    }
   },
   "source": [
    "neuron = MyNeuron(in_size=100, tau=10*u.ms, V_th=1*u.mV)\n",
    "brainstate.nn.init_all_states(neuron)\n",
    "\n",
    "# Create appropriate input current\n",
    "input_current = jnp.ones(100) * 0.5 * u.nA"
   ],
   "outputs": [],
   "execution_count": 79
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Performance Tips\n",
    "\n",
    "1. **Use JIT compilation** for repeated simulations:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.814559Z",
     "start_time": "2025-11-13T09:26:27.810192Z"
    }
   },
   "source": [
    "@brainstate.transform.jit\n",
    "def simulate_step(input):\n",
    "    neuron(input)\n",
    "    return neuron.V.value"
   ],
   "outputs": [],
   "execution_count": 80
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "2. **Batch multiple trials** for parallelism:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.848829Z",
     "start_time": "2025-11-13T09:26:27.840789Z"
    }
   },
   "source": "brainstate.nn.init_all_states(neuron, batch_size=100)",
   "outputs": [
    {
     "data": {
      "text/plain": [
       "MyNeuron(\n",
       "  in_size=(100,),\n",
       "  out_size=(100,),\n",
       "  spk_reset=soft,\n",
       "  spk_fun=InvSquareGrad(alpha=100.0),\n",
       "  tau=10 * msecond,\n",
       "  V_th=1 * mvolt,\n",
       "  V=ShortTermState(\n",
       "    value=~float32[100] * mvolt\n",
       "  ),\n",
       "  spike=ShortTermState(\n",
       "    value=ShapedArray(float32[100])\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 81,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 81
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "3. **Use appropriate data types**:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.879178Z",
     "start_time": "2025-11-13T09:26:27.874662Z"
    }
   },
   "source": [
    "# Float32 is usually sufficient and faster\n",
    "brainstate.environ.set(precision=32)"
   ],
   "outputs": [],
   "execution_count": 82
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "4. Use soft reset for higher firing rates:"
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.912742Z",
     "start_time": "2025-11-13T09:26:27.908977Z"
    }
   },
   "source": [
    "# Use soft reset for higher firing rates\n",
    "neuron = brainpy.state.LIF(100, tau=10*u.ms, spk_reset='soft')"
   ],
   "outputs": [],
   "execution_count": 83
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "5. Use hard reset for precise spike timing:"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.923213Z",
     "start_time": "2025-11-13T09:26:27.919965Z"
    }
   },
   "cell_type": "code",
   "source": [
    "# Use refractory period for precise timing\n",
    "neuron = brainpy.state.LIFRef(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    tau_ref=2. * u.ms,\n",
    "    spk_reset='hard'\n",
    ")"
   ],
   "outputs": [],
   "execution_count": 84
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "6. Use refractory period for precise timing"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:26:27.959276Z",
     "start_time": "2025-11-13T09:26:27.954296Z"
    }
   },
   "cell_type": "code",
   "source": [
    "neuron = brainpy.state.LIFRef(\n",
    "    100,\n",
    "    tau=10*u.ms,\n",
    "    tau_ref=2*u.ms,\n",
    "    spk_reset='hard'\n",
    ")"
   ],
   "outputs": [],
   "execution_count": 85
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "7. Adaptation creates bursting patterns"
  },
  {
   "cell_type": "code",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-11-13T09:27:20.880214Z",
     "start_time": "2025-11-13T09:27:20.862053Z"
    }
   },
   "source": [
    "neuron = brainpy.state.ALIF(\n",
    "    in_size=100,\n",
    "    V_rest=-65. * u.mV,\n",
    "    V_th=-50. * u.mV,\n",
    "    V_reset=-65. * u.mV,\n",
    "    tau=10. * u.ms,\n",
    "    tau_a=200. * u.ms,\n",
    "    spk_reset='soft'\n",
    ")\n",
    "brainstate.nn.init_all_states(neuron)\n",
    "\n",
    "# Adaptation creates bursting patterns\n",
    "neuron = brainpy.state.ALIF(\n",
    "    100,\n",
    "    tau=10*u.ms,\n",
    "    tau_a=200*u.ms,\n",
    "    beta=0.01,\n",
    "    spk_reset='soft'\n",
    ")"
   ],
   "outputs": [],
   "execution_count": 89
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "Neurons in `brainpy.state`:\n",
    "\n",
    "✅ **Multiple models**: IF, LIF, LIFRef, ALIF\n",
    "\n",
    "✅ **Physical units**: All parameters with proper units\n",
    "\n",
    "✅ **Flexible reset**: Soft or hard reset modes\n",
    "\n",
    "✅ **Training-ready**: Surrogate gradients for learning\n",
    "\n",
    "✅ **High performance**: JIT compilation and batching\n",
    "\n",
    "✅ **Extensible**: Easy to create custom models\n",
    "\n",
    "## Next Steps\n",
    "\n",
    "- Learn about synapses to connect neurons\n",
    "- Explore projections for network connectivity\n",
    "- Follow tutorials for hands-on practice\n",
    "- See docs for network examples"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Ecosystem-py",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
